#!/usr/bin/env python
#Copyright (c) 2011 Isaac Dawson (WBTS Project)
#Permission is hereby granted, free of charge, to any person obtaining a copy 
#of this software and associated documentation files (the "Software"), to deal 
#in the Software without restriction, including without limitation the rights 
#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
#copies of the Software, and to permit persons to whom the Software is furnished
#to do so, subject to the following conditions:
#
#The above copyright notice and this permission notice shall be included in all
#copies or substantial portions of the Software.
#
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
#THE SOFTWARE.
import os

class WBTSStorage(object):
    mConnString = ""
    mDbType = ""
    def __init__(self, *connect_args):
        self.mConnectString = connect_args[0]
        return
    
    def connect(self):
        """
    Used for obviously connecting to a datastore. Should return a deferred
    success of 0.
        """
        return

    def createTable(self, tbl_name, tbl_func=None):
        """    
    Creates a new table and assigns it as an attribute. If the table already
    exists (the attribute has been set) then it returns a deferred of 1.
    @returns
    (deferred) 0 - table created.
    (deferred) 1 - already exists
        """
        return

    def dropTable(self, tbl_name):
        """
    This method should not only delete the attribute (delattr) and call the
    Table's drop method, this should return a deferred of 0 for success 1
    otherwise.
        """
        return
    
    def _save(self):
        """
    Only really used for storage systems that save to disk. (WBTSPydictDB
    for example). Returns a deferred 0 for success, 1 if an error occurred.
        """
        
    def _load(self):
        """
    Same as above, this should restore every attribute (WBTSTableObject) on a
    successful load to our db object. Returns True if the load was OK, False if
    an error occurred.
        """
    
    def _parseConnectionString(self):
        return
    
    def disconnect(self):
        """
    Disconnects the database. Returns 0 on success. Also returns 0 if DB is not
    connected. Throws a error otherwise.
        """
        return
    
    def __getitem__(self, name):
        return getattr(self, name)
        
    
    
class WBTSTableObject(object):
    def find_one(self, search_key=None):
        """
    Find a single record
    @params
    search_key - A dictionary of keys/values to be used to find a record
    @returns
    A deferred which results in a dict object of the first record found
    or an empty dict {} if nothing found.
        """
        return

    def find(self, search_key=None, skip=0, limit=-1):
        """
    Finds a splice of records (starting at skip up to skip+limit). 
    @params
    search_key - A dictionary of keys/values to be used to find records.
    skip - an integer of the # of records to skip ahead
    limit - the number of records to return, if -1 returns rest of records
            starting from skip.
    @returns
    A deferred which will return a list object of records between skip
    and skip+limit Ex: (table.records[skip:skip+limit])
        """
        return

    def insert(self, record):
        """
    Inserts a record (dictionary object) of data into the table.
    @params
    record - a dictionary object of our data. Keep in mind SQL versions will
    be strict about the data type, pydictdb and mongodb don't care :).
    @returns
    A deferred of 0 for success and 1 for failure.
        """
        return

    def remove(self, search_key):
        """
    Removes ANY record that maches the values from search_key.
    @params
    search_key - a dictionary of key/values to be used to find a record.
    @returns
    A deferred of 0 for success and 1 for failure or record not found.
        """
        return

    def count(self):
        """
    Returns a deferred of the number of records.
        """
        return
    
    def drop(self):
        """
    Drops the current database table.
    @returns
    A deferred value 0 for success 1 for error
        """

class WBTSStorageException(Exception):
    """
    Our handler for storage related errors."
    """
